<html>
<head>
    <title>XBRLAPI installation suggestions</title>
    <link rel="stylesheet" href="/css/styles.css" type="text/css"/>
    <script type="text/javascript">
        var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
        document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
    </script>
    <script type="text/javascript">
        try {
            var pageTracker = _gat._getTracker("UA-11401995-1");
            pageTracker._setDomainName("none");
            pageTracker._setAllowLinker(true);
            pageTracker._trackPageview();
        } catch (err) {
        }</script>
</head>


<body>

<div class="logo_container">
	<span class="logo">
		<a class="title" href="/">XBRLAPI</a>
	</span>
	<span class="logo_subscript">
		<a class="title" href="http://en.wikipedia.org/wiki/Free_and_open_source_software">Free Open-Source Software</a>
	</span>
</div>

<div id="navcontainer">
    <form action="http://www.xbrlapi.org/search.html" id="cse-search-box">
        <div>
            <input type="hidden" name="cx" value="partner-pub-3957505011939955:jqid48zd81o"/>
            <input type="hidden" name="cof" value="FORID:10"/>
            <input type="hidden" name="ie" value="ISO-8859-1"/>
            <input type="text" name="q" size="31"/>
            <input type="submit" name="sa" value="Search"/>
        </div>
    </form>

    <script
            type="text/javascript"
            src="http://www.google.com/cse/brand?form=cse-search-box&amp;lang=en">
    </script>

    <ul id="navlist">
        <li><a href="/">Home</a></li>
        <li><a href="testConfigurationFile.html">Configuration Properties</a></li>
    </ul>

    <script type="text/javascript"><!--
    google_ad_client = "pub-3957505011939955";
    /* XBRLAPI site */
    google_ad_slot = "4927123290";
    google_ad_width = 160;
    google_ad_height = 600;
    //-->
    </script>
    <script type="text/javascript"
            src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
    </script>

</div>
<div class="content">

    <h1>Using Maven with XBRLAPI</h1>

    <h2>Overview</h2>

    <p>Maven is a build management tool that can be used to simplify the process
        of building XBRLAPI, managing the dependencies on third party JAR files, and
        automating the process of running unit tests.</p>

    <h2>Check the XBRLAPI source code out from the SVN repository</h2>

    <p>See the <a href="https://sourceforge.net/svn/?group_id=135539">
        Sourceforge instructions</a> on getting a
        copy of the XBRLAPI SVN repository. At its simplest you should use the
        following command at the command line if you have an appropriate SVN client
        installed in your own environment:<br/>
        <code> svn co https://xbrlapi.svn.sourceforge.net/svnroot/xbrlapi xbrlapi</code></p>

    <h2>Install Maven 2.0 or later</h2>

    <p>Download <a href="http://maven.apache.org/">Maven 2.0</a> or later.</p>

    <p>You download an archive file that needs to be extracted to the local file system. Once the
        archive file is extracted, there is no additional installation process as such. However, you may
        want to configure your environment to find the <code>mvn</code> command regardless of the current
        directory.</p>

    <p>Verify the installation by running <code>mvn --version</code>.</p>


    <h2>Modify the POM files for your own environment</h2>

    <p>The XBRLAPI source has been divided into a number of different modules. Each module
        has its own POM.xml file. These module POM files are all referenced by the POM file in the
        root directory of the XBRLAPI source code. These POM files contain some information about the
        structure of the local file system that you will need to tailor to your own environment.</p>

    <p>The POM files for each module (found in the module-xxx) directories) all define a
        surefire-plugin property, called <code>xbrlapi.test.configuration</code> that identifies
        the location of the test configuration properties file. This location needs to specify
        the location of the test properties file that you want to use.</p>

    <p>The POM files also specify the location of the log4j.xml logging configuration file that
        should be used in your own environment. This file location is specified at the end of the POM
        files in the test properties section. In most cases, if you have checked out the full XBRLAPI
        source tree, then a workable log4j.xml file will have been checked out into a conf directory.
        In such cases, the POM files will already refer to this log4j configuration file and no POM
        file modifications will be necessary.</p>

    <p>The POM file for the bdb-xml project, contained in the <code>module-bdb-xml</code> directory
        also specifies the location of the Oracle Berkeley DB XML database binaries. This needs to be
        set to the appropriate location in your own environment. See the <code>argLine</code> element
        in the surefire plugin configuration. Without setting this correctly, it will not be p<a class="title"
                                                                                                 href="http://en.wikipedia.org/wiki/Free_and_open_source_software">Free
            Open-Source Software</a>ible
        to run the unit testing for the data store based on the Oracle Berkeley DB XML database. It needs
        to specify to the directory containing the binary library files that operate the database you are using.</p>

    <p>If you have ideas on how to make the POM files more portable acr<a class="title"
                                                                          href="http://en.wikipedia.org/wiki/Free_and_open_source_software">Free
        Open-Source Software</a> platforms and
        environments then please put them forward.</p>

    <h2>Sort out dependencies that are not supported by online Maven repositories</h2>

    <p>Maven does a great job of providing the necessary JAR files based upon the
        dependencies documented in the Maven program object models (POM files). However,
        some of the JAR files that XBRLAPI has dependencies on are not available from
        the online Maven repositories. These dependencies have to be addressed manually by
        placing the appropriate JAR files into the local Maven repository.</p>

    <p>Adding a new custom JAR to the local MAVEN repository is done as follows (using eXist 1.4 as an example):</p>

    <p><code>mvn install:install-file -DgroupId=exist -DartifactId=exist -Dversion=1.4 -Dpackaging=jar
        -Dfile=exist-1.4.jar</code><br/>
        This needs to be run from the directory containing the JAR file to be added to the local repository.
    </p>

    <p>
        A <a
            href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/java/lib/install_jars_in_local_maven_repository.sh?view=log">shell
        script</a> that takes care of this for you is available from the source repository. It will need
        to be run from within the directory containing the <a
            href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/java/lib/">relevant
        JAR files</a>.
    </p>

    <p>Depending on the modules that you want to use, the following third party JAR files
        need to be inserted into the local MAVEN repository using the approach
        described above. Note that, if you do not want to use a persistent data store then none of these
        JAR files are required in the local MAVEN repository.</p>

    <p>The up-to-date dependencies for each module released by the XBRLAPI project
        are documented in the Maven POM files for the project and its modules</p>

    <ul>
        <li><a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/pom.xml?view=log">Project POM</a></li>
        <li><a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/module-api/pom.xml?view=log">XBRL API</a>
        </li>
        <li><a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/module-bdbxml/pom.xml?view=log">Oracle
            Berkeley XML Database data store</a></li>
        <li>
            <a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/module-examples/pom.xml?view=log">Examples</a>
        </li>
        <li><a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/module-exist/pom.xml?view=log">eXist XML
            Database stand-alone data store</a></li>
        <li><a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/module-exist-embedded/pom.xml?view=log">eXist
            XML Database embedded data store</a></li>
        <li><a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/module-utilities/pom.xml?view=log">Utilities
            - common components required by other modules</a></li>
        <li><a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/module-xdt/pom.xml?view=log">XBRL
            Dimensions module</a></li>
        <li><a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/module-xlink/pom.xml?view=log">XLink
            module</a></li>
        <li><a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/module-xmlbase/pom.xml?view=log">XML Base
            module</a></li>
        <li><a href="http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/module-xpointer/pom.xml?view=log">X-Pointer
            module</a></li>
    </ul>

    <h2>Running Maven</h2>

    <p>The XBRLAPI source has been divided into a number of different modules. Each module
        has its own POM.xml file. These module POM files are all referenced by the POM file in the
        root directory of the XBRLAPI source code. To perform a Maven operation on the entire XBRLAPI
        installation, issue the Maven command from the root directory of the XBRLAPI checked out from
        the SVN repository. For example, to build and test all modules, run <code>mvn test</code>
        from the command line when the current directory is the XBRLAPI root directory.
        To build, test and install all modules, run <code>mvn install</code> from the command
        line when the current directory is the XBRLAPI root directory.</p>

    <p>The same commands can be run from the <code>module-xxx</code> directory to just operate
        on that specific module. This is the approach that will need to be taken if you decide
        not to install the necessary custom JAR files required by the persistent data store modules.</p>

    <p>Note that installation involves copying the generated JAR file(s) into the local Maven repository, ready
        to be referenced as dependencies by other projects or modules.</p>

    <p>See the <a href="http://maven.apache.org/guides/index.html">Maven documentation</a> for more
        details on what can be done with Maven.</p>

    <p>
        <a href="http://sourceforge.net/projects/xbrlapi"><img
                src="http://sflogo.sourceforge.net/sflogo.php?group_id=135539&type=11" width="120" height="30"
                border="0"
                alt="Get Java XBRL API implementation at SourceForge.net. Fast, secure and Free Open Source software downloads"/></a>
    </p>

</div>

</body>
</html>
